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ABSTRACT 


This document describes the QuickDraw graphics package, heart of the 
Macintosh User Interface ToolBox routines. It describes the 
conceptual and physical data types used by QuickDraw, the procedures 
and functions available in QuickDraw, and the details of preparing, 
compiling, and linking a program for use on the Macintosh. 
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INTRODUCTION TO QUICKDRAW 


QuickDraw ig a set of graphics procedures, functions, and data types 
that allow a Pascal or assembly-language programmer of Macintosh to 
perform highly complex graphic operations very easily and very quickly. 


This document introduces you to QuickDraw and its programmatic 
interface. It covers the graphic concepts behind QuickDraw, as well as 
the technical details of the data types, procedures, and functions you 
will use in your programs. It also describes the fundamentals of 
preparing, compiling, and linking a program to run on Macintosh. 


What QuickDraw Can Do 
QuickDraw allows you to divide the Macintosh screen into a number of 
individual areas, eng ah ehin each area you can draw-many things: - 


- Straight lines of any length and width; 


ae 


Alled ie 
Rectangles, either solid or hollow; 


Circles and ovals, also either solid or hollow; 


Rectangles with rounded corners, solid or hollow; peas 
Any other arbitrary shape or collection of shapes, again sens ove~ 
solid or hollow; cub 


Images defined dot-by-dot and stored in a file or in the program 
itself; aio 
Text characters in a number_of proportionally-spaced fonts, with 

ariations that includecembolden italiciging, shadowing, and 

Tetterspacin : 
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Figure 1. Samples of QuickDraw’s Abilities 


In addition, ies has some other abilities that you won’t find in 
many other graphics packages. These abilities take care of most of the 
“housekeeping "(:) the trivial but time-consuming overhead that’s 
necessary to keep things straightencd up-but ere—seakiy bothersome to 


iS canal Among thepe. are: Ln’ orden 
ay Pcs. I tet ed L oe Gi uick De deve | 
- The ability to define many“distinct “ports” on the screen, , ec 
with its own complete drawing 


environment@) = its own coordinate 
system, drawing location, character set, location on the screen 
etc. You can switch from one drawing environment\to another with. ae 


just one command. “pk, P ep C \ 
Full and complete ‘:lipping! to arbitrary eeeienn. It’s like a 
super-duper coloring book that won*t let you color outside of the 
lines. You don’t have to worry about accidentally drawing over 
something else on the screen, or drawing off the screen and 

trashing memory. 


Off-screen drawing. Anything you can draw on the screen, you can 
draw into an off-screen buffer, so you can prepare an image for an 
output device without disturbing the screen, or you can prepare a 
picture and move it onto the screen very quickly. 


And QuickDraw lives up to its name! It is very fast. The speed and 
responsiveness of the Macintosh user interface is due primarily to the 
speed of the QuickDraw package. You can do good-quality animation, 

fast interactive graphics, and complex yet speedy text displays using 
the full features of QuickDraw. Ths p Meta nin Re eke ER t Ltt 
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How To Use QuickDraw : 
QuickDraw has no user interface of its own; you must write and compile 
(or assemble) a Pascal (or assembly-language) program that includes the 
proper QuickDraw calls, link the resulting object code with the 
§ QuickDraw code, and execute the linked object file. per 


Some programming models are supplied at the end of this manual; they | 
show the structure of a properlyorganized QuickDraw program. What’s 
best for beginners is to obtain a machine-readable version of pone of 
these, programs (see the Macintogh software coordinator), read through 
che -obake and using the superstructure of the program as a “shell, 

mo y to suit your own purposes. Once you get the hang of writing 
programs inside the presupplied shell, you can work on changing the 
shell itself. 


In the final Macintoshes, QuickDraw will be stored permanently in the 

ROM memory (right now, it resides in high RAM). All access is made 

through an indirection table in low RAM. When you write a program that tty? 
uses QuickDraw, you link it with this indirection table. Each time you dn “Hi 
call a QuickDraw procedure or function, or load a predefined constant, * Jv 

the request goes through the table into QuickDraw. Youll never access 

any QuickDraw address directly, nor will you have to code constant 

addresses into your program. The linker will make sure all address 

references get straightened out. 


QuickDraw can be used from either Pascal or( 68069 machine language. To 
be clear, concise, and more intuitive, this manual gives all examples 
in their Pascal form; a section near the end describes the details of 
the machine language interface to QuickDraw. 


QuickDraw includes only the graphics and utility procedures and 
functions you*ll need to create graphics on the screen. Keyboard 
input, mouse input, and larger user-interface constructs such as 
windows and menus are implemented in separate packages that use 
QuickDraw but are linked in as separate units. You don’t need these 
units in order to use QuickDraw; however, you“1l probably want to get 
the documentation foréach of the above)and learn how to use them with 
your Macintosh programs. ee 

Colvania d Wiha ; | 
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ABOUT THIS MANUAL 
Lisa 
We assume that you are Cupane faniliaDwith programming in,Pascal and 
assembly language; this graphics package is for programmers, not end 
users. 


The manual begins by stepping back a little and looking at the 
mathematical concepts that form the foundation for QuickDraw: 
coordinate peters. points, and rectangles. The mathematics are then 
associated WO raphic entities that can be seen on the screen. Once 
you understand these concepts, read on about the graphic entities based 
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4—- — 
on those concept st) how the mathematical world of planes and rectangles 
is translated into the physical phenomena of light and shadow. 


Then comes sone aetiatte t sg, soae_of thd miscellaneous parts 
of QuickDraw, such as using evel graphics ports at-once; and 
manipulating character fonts. Following this discussion is a summary 
of the basic drawing process. This tells you how to structure your 
programs so that everything happens in the right order and in the right 
way. This is a particularly important section: it’s got a lot of 
helpful hints on how to build programs that work right the first time. 


Finally, there“s the detailed, blow-by-blow description of every XK 
QuickDraw procedure and function, their parameters, calling protocol, 
effects, side effects, ete? all the that you”ll refer—to-aay~_ 
time you write a program for Macintosh. Its a lengthy section, 

because there are a lot of QuickDraw calls. But the calls and the 
parameters are summarized in an appendix for quick reference once ut ) 


you”ve learned what they do. 
yeu sa tee wee 


} : Y 
THE MATHEMATICAL FOUNDATION OF QUICKDRAW 


To create graphics that are both precise and pretty requires not 
supercharged features but a firm mathematical foundation for the 
features you have. If the mathematics that underlie a graphics package 
are imprecise or fuzzy, the graphics will be, too. QuickDraw defines 
some clear mathematical constructs that are widely used in its 
procedures, functions, and data types: the coordinate plane, the 


point, the rectangle, and the region. ; 
ae ‘i focat’s ) 


The Coordinate Plane b 
All information about @aséteen, or movement that 
you give to QuickDraw is in terms of coordinates on a plane. The 
coordinate plane is a two-dimensional grid: 
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Figure 2. Coordinate Plane 
There are two distinctive features of the QuickDraw coordinate plane: 
- All grid coordinates are integers; and 
- All grid lines are infinitely thin. 


These concepts are important! First, they mean that the QuickDraw 
plane is finite, not infinite (although it is very large). Horizontal 
coordinates range from -32768 to +32767, and vertical coordinates range 
from -32768 to +32767 also. (An auxiliary package is available that 
maps real Cartesian space, with X, Y, and Z coordinates, onto 
QuickDraw"s @B) integer coordinate system.) 

Second, they mean that all elements represented on the coordinate, plane 
are mathematically pure. Mathematical calculations using integer 
arithmetic will produce intuitively correct results. If you keep in 
mind that coordinates are infinitely thin (and a couple more related 
concepts), you“ll never have “endpoint paranoia"--the confusion that 
results from not knowing whether that last dot is included in the line 
or not. 


Points 
On the coordinate plane are 4,294,967,296 unique points; each point is 
at the intersection of a horizontal grid line and a vertical grid line. 
As the grid lines are infinitely thin, a point is infinitely small. Of 
course there are more points on this grid than there are dots on the 
Macintosh screen: when using QuickDraw you associate small parts of 
this grid with areas on the screen, so that you aren”t bound into an 
arbitrary, limited coordinate system. 
The coordinate origin (f,%) is in the middle of the grid. Horizontal 
coordinates increase as you move left to right, and vertical 
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coordinates increase as you move Cop to bottom. This is the way both a 
TV screen and a page of English text are scanned: from the top left to 
the bottom right. 


You can store the coordinates of a point into a Pascal variable whose 
type is defined by QuickDraw. The type Point is a record of two 
integers, and has this structure: Awan 
oo N ypu Ged 9) es 
TYPE\WHSdlect = (Wh)? 


@: (v : INTEGER; 
h : INTEGER); 


1: (wh: ARRAY[VHSelect] OF INTEGER) | 


END; 


. The ease variantjallows you to access the vertical and horizontal 

‘ components of a point either individually or as an array. For example, 
if the variable Fermitr were declared to be of type Point, the 
references Reyes 


v, 
Keraia.vh[v] Fereia.vh(h] 


would all’refer to the coordinate Oists of the point. 


Rectangles 


Any two points can define the top left and bottom right corners of a 
rectangle. As these points are infinitely small, the borders of the 
rectangle are infinitely thin. 


Borrom 
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Rectangles oe ea to definet ctivéSareas on the screen, to assign 
coordinate systems to graphic entities, and to specify the locations 
and sizes for. ver ious, drawing commands.y All these uses of rectangles 
are described in the section "Graphi Operations on Rectangles”. 
QuickDraw also allows you to perform many mathematical calculations on 
rectangles: changing their sizes, shifting them around, etc. 


( hand) 
Remember that rectangles, like points, are mathematical 
concepts that have no direct representation on the 
screen. The association between these conceptual 
elements and their physical representations is made by a 
bitMap, described below. 


The data type for rectangles is called the Rect, and consists of 
integers or two points: 


TPE Rect = RECORD CASE INTEGER OF 


INTEGER; 
INTEGER; 
INTEGER; 
INTEGER) 


1: (topLeft : Point; 
botRight: Point) 


END; 


Once again, the record variant allows you to access a variable of type 

Rect either as four coordinate boundaries or as two diagonally opposing 
corner points. Combined with the record variants for points, all of 

the following references to the Rect named Train are legal: yak a 


deAtmvassh lesions chaz haanaebceatasrdetunsaantepplett Type 3 


Train.topLeft.....++++++-Train.botRight....+++..Sufoint type 3 


Train.stopssssceeeeeeeeseeTrainsleftesseseeeeeseeSuINTEGER Type f 
Train.topLeft.v.........-Train.topLeft.h..se+e-epaINTEGER 1; 
Train.topLeft.vh[v]......Train.topLeft.vh[h]....+.sINTEGER , 


Train.bottom....ccescceeeTraineright.....-.22eee6e INTEGER 
Train. botRight.v........eTrain.botRight.h......-..INTEGER | 
Train.botRight.vh[v].....Train.botRight.vh[{h].....INTEGER 


If the bottom coordinate of a rectangle is not greater 
than the top, or the right coordinate is not.greater than 
the left, then the rectangle is not a rectangle. All , 
operations that use that rectangle will have no effect 
whatsoever. 
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__ Regions 

Unlike most fraphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at that), QuickDraw has the unique and 
amazing ability to gather an arbitrary set of(spatYally 

into a structure called a region, and perform COWprex yet rapid 
manipulations and calculations on such structures. This remarkable 
featur&willynot ontyymake ur standard programs simpler and faster, 
but will let you perform ofectattons that would otherwise be nearly” 
impossible; it is fundamenfal to the Magintosh user interface. 


You define a region by Grawing) Lines : rectangles, ovals, 
ytounded-corner_rectangles 7 OF, other, regions The outline of a region 

is mathematically definéd=as ome or moré closed loops. A region can be 

concave or convex, can consist\of one area\or many isjoint areas, and 


Figure 4. Regions 
fv 
Because a region can be any arbitrary area{on the coordinate plane, it 
takes a variable amount of information to store the outline of a 
region. The data structure for a region, therefore, is a 
variable-length entity with two fixed fields at the beginning, followed 
by a variable-length data field: 


+YpE egion = RECORD {c~ 
gnSize : INTEGER; w \ut 


‘KenBBox : Rect: wd a v) 


{optional region definition data} 22” 


Mer ie 
END; (Me pl’ 
the XgnSize field contains the size, in bytes, of the(region variable 


The KenBBox field is a rectangle which completely encloses the region. 
For example, if the variable Lumbar is a region, then the field 
Lumbar .RgnBBox.top contains the minimum vertical coordinate of all 
points in the region. 
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The simplest region is a rectangle; in this case, the rgnBBox field 
serves to define the entire region, and there is no optional region 
data. For rectangular regions (or empty regions), the rgnSize field 
contains 1.} elk 


As regions are of variable size, they are stored dynamically on the 
heap, and the Memory Manager moves them around as their sizes change. 
Being dynamic, a region can be accessed only through a pointer; but 
when a region is moved, all pointers referring to it must be updated. 


For this reason, all regions are accessed through handles, which point 


to one raster pointer which in turn points to the region. 
cyte Tpe’ 
G Seis 
4N? PenPtr Region; 
RgnHandle “RenPtr ; 


When the Memory Manager relocates a region’s data in memory, it updates 
only the XenPtr master pointer to that region. The references through 
the master pointer can find the region’s new home, but those references 
that pointed directly to the region’s previous position in memory now 
point at dead bits. To access individual fields of a region, use the 
region handle ang double indirection: 


~Steve} -rgnSize Size of region whose handle is Steve 
*. rgnBBox Boundary box of same region 


Steve*.rgnBBox Syntactically incorrect; will not compile 
if Steve is a rgnHandle 


Regions are created by a QuickDraw function which allocates space for 
the region, creates a master pointer, and returns a XgnHandle. When 
you’re done with a region you can dispose of it with another QuickDraw 
call, which frees up the space used by the region. Only these calls 
allocate or deallocate regions; DO NOT use the Pascal procedure NEW to 


create a new FeEtOnC AD) 


Many calculations can be performed on regions. A region can be 
or bataied J Lane rates any two regionsyQuickDraw can find their union, 
intersection, ference, and exclusive-OR; it can also determine 
whether a given point or rectangle intersects a given region, etc. 
There G6 of course a set of graphi operationgy on regions to,draw or 
outline Phem on the screen, QW (fart PROMO TET 


As 
The outline of a region is _byagraphi a4 


operations, which are described in the section “Pen and Drawing 


Procedures". ? VL sh ee aia, 
ct Zl i) J 


Vey piu 


GRAPHIC OBJECTS 
Coordinate planes, points, rectarigles, and regions are all good 


mathematical models, but they aren”t really graphic elements--they 
don’t have a direct physical appearance. Some graphic entities that do 
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have a direct graphic interpretation are the bit image, pattern, 
cursor, and bitMap. This section describes the data structure of these 
graphic entities and how they relate to the mathematical constructs 
described above. The next section begins to describe the graphic 
operations that you can perform with QuickDraw to draw pictures. 


The Bit Image 
A bit image is a collection of bits in memory which have a rectilinear) 
representation. Take a collection of words’ in memory and lay them end 
to end so that bit 15 of the lowest-numbered word is on the left and 
bit @ of the highest-numbered word is on the far right. Then take this 
array of bits and divide it, on(byt3 boundaries, into a number of 
equal-size rows. Stack these rows vertically so that the first row is 
on top and the last row is on bottom. 


First 


Row 

Width | 
is 
8 bytes 


Figure 5. A Bit Image 


The result is a matrix like the above-~rows and columns of bits, with 
each row containing the same number of bytes. The number of bytes in 
each row of the bit image is called the row width of that image. 


A bit image can be stored in any static or dynamic variable, and can be 
of any length that is a multiple of the row width. 
98, 304 


The Macintosh screen itself is one large visible rE 2 The upper 
bytes of memory is displayed as a matrix of [IV AEED 
scr€éeen? each bit corresponding to one pixel. ere s value is 9, 


its pixel is white; if the bit”s value is 1, the pixel is black. 


The screen ispasge els tall and aed pixels wide, and the row width of 
its bit image istZs/bytes. Each Pixel i the screen is square; the 


pre 
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( hand) 
As each pixel on the screen represents one bit in a ve amply 
image, whenever this document says or you Sie, ) 
: substitute “pixel. , \ 


" x Ne 
: x . Xs ee ae ODA 
wr \ an Ray y 
Patterns y 


“A pattern is a 64-bit image} organized as-ga -by-8-bit square, which 
is used to define a repeating or tong eae. Patterns can ‘be 
used to draw with, to fill an area, ae ae as the source for a 
bitwise operation. Me 


ee ee areas wiswe the same pattern - 
presuces-a-continuous, coordinated pattern¢ QuickDraw provides 57 15 p 
predefined patterns for White, Black, Gray, LtGray, and DkGray. Any 
other 64-bit variable or constant can be used as a pattern, too. The 
data type definition for a pattern is as follows: 


{\Pé Pattern = PACKED ARRAY[@..7] OF 9.255 


The row width of a pattern is 1 byte. 


9 5, Zoe 
The tMap 
When you combine the physical lentity of a bit image with the conceptual 
entities of the coordinate ¢rid)and rectangle, you get a bitMap. A 
bitMap is a,descriptor that has three parts: a pointer to a bit image 
1 b: ectangle which 
k Notice 
“STtMap”, as we will use the term, does not actually include the 
bits themselves: a bitMap is a descriptor containing a pointer to a 
bit image. 


- Because a bitMap points to a bit image, there can be several bitMaps 

. extant simultaneously that all impose different coordinate systems on 
the same bit image. This important feature is explained more fully in 
“Coordinates in grafPorts", below. 


xe 


él - 


4m 
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base Addr 
TOW BYTES | 
bows 


2 an any OP we an ee ab PE a ae Eee a 


sees ep 


Figure 6. A bitMap 


The data structure of a bitMap follows: 


Are bitMap = RECORD 


baseAddr 
rowBytes 
bounds 


END* 
yy 


The baseAddr field is a pointer to the beginning of the bit image in 

memory, and the rowBytes field is the number of bytes in each row of 

the image. Both of these should always be even: a bitMap should 

always begin on a word boundary, and contain an integral number of 
_.words in each row. 


C 
G | —_ aa 
The bounds field is a voundagk feng) that both encloses theG@ctive) 
- area of the bit image and imposedVa coordinate system upon it. G 
relationship of the bound rectangle and bit image in a bitMap is 


simple yet very important. First, a few general rules: mal 


a: jus 
- Bits in a Vitale 11 between points on the coordinate ee e 
— ann 


- A rectangle divides a bit image into two sets of bits: those bits ¢ 
inside the rectangle and those outside the rectangle. ay, 
‘ UU 


- A rectangle that is H points wide and V points tall encloses 


maar ph ais ae ae CH-I ) cd (vet ) 


The top left_co of the bounding rectangle is aligned around the 

The width of the rectangle determines how 
many bits of one row afe logically owned by the bitMap; the 
relationship . 
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CKoMap.rowBytes >= @(Map.bounds.right-Map.bounds.left) x 


must always be true. The height of the rectangle determines how many o 
rows of the image are logically owned by the bitMap; the relationship AY 
ae 


SIZEOF(Map.baseAddr~) >= (Map.bounds.bottom-Map. bounds.top) yw 
* Map.rowBytes 


“Woe i ( tes in | it we ic Ae (height) # widtle of ane tang — 


must always be true to ensure that th umber of bits in the logical 
bitMap area is not larger than the number of bits in the bit image. 


Normally, the bound rectangle completely encloses the bit image: 
the width of the bound feel rectangle is equal to the number of bits in 
one row of the image, and the height of the rectangle is equal to the 
number of rows in the image. If the rectangle is smaller than the 
dimensions of the image, the least significant bits in each row, as 
well as the last rows in the image, are not affected by any operations 
on the bitMap. 


iF \ 
krvnkany pectongfer th the) 
muds impoges a coordinate system on the image. Because bits — 


fall between coordinate points, the coordinate system assigns integer 

‘values to the lines that border and separate—b: e—bit fir ve arple 
positions themselves. (¥f a bitMap is assigned the bound rectangle P / 
(16,-$) (3§,-$) (19,8) (39,8), the bottom right bit in the image will 

be between/hotizontal cootdinates 34 and 38, and between vertical 

coordinates 7{and 8. 


V, y / 
EET eye 
EEE EEE 
a fet trey | He 


VAAL 
143 


itt SRREREET 34 

CLY tli VY, 
EEEEEEEEEEEHEEEEEEE EE el 47 

(10,8) Ct, IY 


Figure 7. Coordinates and bitMaps 
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Cursors 


A cursor is a small image) that appears on the screen and is controlled 
by the mouse. Cursors are defined as a 256-bit image, a 16-by-16— Lit 
square. The row width of a cursor is 2 bytes. 


8 


Figure 8. Cursors 


“ 


A cursor has three fields: a l16-word data field that contains the 


“image itself, a l6-word mask field that contains information about the 
screen appearance of each bi and’a —hotSpot" point that 


aligns the cursor with the pos on of the mouse. t “Low we 
pu ois 


Cursor = RECORD f 

data = ARRAY(@..15] OF/ INTEGER; 
mask = ARRAY[@--15] OF INTEGER; 
hotSpot = Point 


END“ a | te 
J nee 
Vr 


The are itd the cursor must begin on a word boundary. opt 


PO DAE in anced 


- The curs appdars on fas on the screen as a l6-by-16-bit square. , Zach bit of 
the quae sopgrs on th two corresponding bits in the eles and! 


" mask#® aud and, if fe nap 4& G, 
(0 Prof 


pata. 


,) ; 
or Y 1 ead under “pee a a 
The hot spot aligns a point in ARP? a bit, a point!) with 
the mouse position. Imagine the rectangle with corners (9,6) and 


er ae the imagef the hotSpot 1s defined In this coordinate 
system. A hotSpot of (%,%) is at the top se of the image; A hotSpot 


of h4 is in the exact center of the - a es Scisa 


Oth ang to SPREE RNE GE. 
eee ae. ake ot - jewhew QUICK. DRAW/QUIKDRAW. 2 
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mouse, the low-level interrupt-driven mouse routines move the cursor’s 
hot spot to be aligned with the new mouse position. 


( hand) 
The mouse position is always, unalterably linked to the 
cursor position. You can’t reposition the cursor through 
software: the only control you have is whether it is 
visible or not, and what shape it will assume. Think of 
it as being hard-wired: if the cursor is visible, it 
always follows the mouse over the full size of the 
screen. 


QuickDraw supplies one predefined cursor, a pointing arrow, named 
Arrow. rr ott od 
Prous eh ons oeerors Feta iene ee ee tt ee a Tr tt pe 
The afPort 
A grafPort is a complete drawing environment that defines how and where 
graphic operations will have their effect. A grafPort is like a 
logical output device: it contains all the information about one 
instance of graphic output that is kept separate from all other 
instances. You can have many grafPorts open at once, and each one will 
have its own coordinate system, drawing pattern, background pattern, 
pen size and location, character font, size, and style, and bitMap i 
which drawing takes place; one statement will instantly switch you fron 
one port to another. GrafPorts are the structures on which we build 
windows, which are fundamental to the Macintosh “overlapping folders” 
user interface. 


A grafPort is a dynamic data structure with ten fields: 


We grafper = “grafPort; eo 
grafPort = RECORD ante * cen) 
BitMap; (447 °° 


4 
_ portBits ™ ort (a 
portRect Rect; Lawhaet +f pil ep ward by avef ford, x 
visRgn RenHandle; (Ardent ts pork Ruck A 
clipRgn RgenHandle; Vy 
Pattern; 


bkPat 
(CharStyle; 
nt; 


chStyle 
Point; 


pnLoc 
INTEGER; 


pnSize 
pnMode 
Pattern 


pnPat 
END? 
> 


ae 08 ee ce ee 40 8 00 08 of 


All QuickDraw operations refer to grafPorts via grafPtrs. You create a 
grafPort with the Pascal procedure NEW and use the resultant pointer in 
calls to QuickDraw. You could, of course, declare a static VAR of type 
grafPort, and obtain a,pointer to that static structure (with the @ 
operator), but as most/ grafPorts will be used dynamically, their data 
structures should be dynamic also. 


> 
ae 
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( hand) 4 
You can access all fields and subfields of a grafPort 
normally, but you should not store new values directly 
into them. QuickDraw has procedures for altering all 
fields of a grafPort, and using these procedures ensures 
‘that changing a grafPort produces no unusual side 
effects. 


The portBits field of a grafPort is the bitMap that points to the bit 
image in memory to be used by the grafPort. All drawing that is done 
in this grafPort will take place in this bit image The default bitMap 
“uses theyte4 ntgs video screen as its bit image, Hat rowBytes of 48 
and kes a bound rectangle of (9,9) (384, 256). The bitMap can be —4 
changed to indicate a different structure in memory: all graphics 
procedures work in exactly the same fashion regardless of whether their 
' effects are visible on the screen. A program can, for example, prepare 
an image to be printed on a printer without ever displayfng the image 
on the screen; or a picture can be developed in an off-screen bitpap 
before being transferred whole to the screen. The coordinate system of 
the grafPort can be changed by altering the coordinates of the 
portBits.bounds rectangle; with a QuickDraw procedure call, you can set 
dm arbitrary coordinate aystend for each grafPort, even if they all use 
the same bit image (i.e. [}regsereen). the eALt 
( prot 
The portRect field is a rectangle that defines a subset of the bitMap 
for use by the grafPort. tg coordinates are in the system defined by 
-the portBit bitMap”s bound rectangle. All drawing done by the user 
or application program is clipped to the inside of this rectangle; the 
portRect usually defines the “writable” interior area of a folder, 
document, or other object on the screen. 


ai? 


7 


= fad 

+ = 
ae 

“SS 


AL, 


le) Lar 


The visRgn field is manipulated by the Window Manager; users and 
programmers will normally never change a grafPort”s visRgn. It 
nse ad that region (remember, an arbitrary area or set of areas) 

$ actually visible on the screen. For example, if you move one 
folder on top of another, the Window Manager (logicaly removes the area 
of overlap from the visRgn of the folder on bottom. When you draw into 
the bottom folder, whatever*s being drawn is clipped to the visRgn so 
that it doesn’t run over onto the top folder. The default visRgn is 
set to the portRect. 
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Figure 9. grafPort Regions 


The clipRgn is an arbitrary region that you can use to limit drawing to 
any region within the portRect. If, for example, you want to draw a 
half circle on the screen, you can set the clipping region to half the 
square that would enclose the whole circle, and go ahead and draw the 
whole circle. Only the half within the clipRgn will actually be drawn 
in the grafPort. The default clipping region is set arbitrarily large, 


and you have full control over its setting. . ts 
Cor drerartid Pater un Her 


The bkPat is a pattern that is used/for filling in the background of a 
picture during erasing or scrollin This pattern, like all other 
patterns, is always drawn aligned with the local coordinates of the 
grafPort. 


The chStyle is a record (see below) that determines the font and style 
of characters drawn in the grafPort. 


The last four fields deal with the graphics pen. Each grafPort has one 
and only one graphics pen, which is used for drawing lines and printing 
text. The pen has four characteristics: a location, a size, a drawing 
mode, and a drawing pattern. 
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ts 137 
Location] 


x Figure 19. A Graphics Pen 
x 

The pen location is a point in the local coordinate system of the 

grafPort (see below). The pen location can be anywhere on the 

coordinate plane: there are no restrictions on the movement or 

placement.of the pen. Remember that the pen location is a point on the 

coordinate:plane, not a pixel in a ey bit Mapa dyn Fas Eick prt he 
§. ® . 
; rut tin 


The pen is rectangular in shape, and ye. a user“definable width and 


height. The default size is a l-by-l-Square; the width and height can 
range from ($,9). to (32767,32767). If either the pen width or the pen 
height -ase less than 1, however, the pen will not draw on the screen. 
1S a Ti Pe 
- The pen.appears-as a rectangle with its upperrleft corner at the 
pen location; it hangs below and to the right of the pen location. 


The pnMode and pnPat fields of a grafPort determine how those bits 
under the pen are affected pnbat is a pattern that is used like 
the "ink" in the pen. The' pattern is drawn on the bitMap aligned with 
the local coordinate system of the grafPort, so that drawing adjacent 
or overlapping areas in the same pattern produces a continuous, 
coordinated pattern. Five patterns are predefined (white, black, and 
three shades of gray); you can create your own tonal or repeating 
pattern and use it as the pnPat. (A utility procedure, called 
StuffHex, allows you to fill patterns easily.) 


The pnMode field determines how the pen pattern is to affect whats 

- already on the bitMap. When the pen draws, QuickDraw first determines 
what bits of the bitMap will be affected, and finds their corresponding 
bits in the pattern. It then does a bit-by-bit evaluation based on the 
pen mode, which specifies one of eight boolean operations to perforn. 
The resulting bit is placed into its proper place in the bitMap. The 
pen modes are discussed in "Transfer Modes", below. 
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The following graphics procedures use the pnSize when drawing: 


LineTo Line 
FrameRect FrameOval 
FrameRoundRect FraneRgn 


These procedures, as well as the ones above, also use the pnMode and 
pnPat when drawing: 


PaintRect PaintOval 
PaintRoundRect PaintRen 


COORDINATES IN GRAFPORTS 


Each grafPort has its own local coordinate system. All fields in the 
grafPort are expressed in these coordinates, and all calculations and 
actions performed in QuickDraw use the local coordinate system of the 
currently selected port. 


Two things are important to remember: 
plans 
- Each grafPort maps a portion of a coordinate guid into a 
similarly-sized portion of a bit image. 


(th Ancrdergy poche it ) 
- The portBits.bounds field defines the local coordinates for a 
grafPort. 


rectangles is very importan Kia 
portBits.bounds is always aligned around the first bit in the bit 
{mage; the coordinates of that corner “anchor” a point on the grid to 
that pixel in the bit image. This forms a common reference point for 7 
multiple grafPorts using the same bit image (such as the screen); given 
a portBits.bounds rectangle for each port, you know that their top left 

. corners coincide. 


As the portBits.bounds rectangle establishes a coordinate system for a 
the port, th, rtRect rectangle indicates the section of the 
coordinate (and thus the bit image) will be usedapfor drawing. 


portRect usually falls inside the portBits.bounds rectangle, but it is 


nnn 
toe 
? 


not required to do SO. eee 
When a new gr Mas created and initialized, its bitMap is q. to 


point to the jMacintosh screen, and both the portBits.bounds and the 
portRect rectangles are set to 384-by-256, rectangles, with the origin 
point (%,) at the top left corner of, che screen W ae 
ane Hig Urea Orde s ft 
the grafPort is always the top left corner 
2 ith the SetOrigin 


procedure; this recalculates 
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be relative to the new origin point. For example, calling the 


uv ve \ Ay 

S(Oakland) 3-9 > , 

 Setorigin(20, 50). po os a 
ae \ : je 


procedure 


216— 
Before SecOrigin After SecOrigin(20,50) | 


Figure 11. Setting Local Coordinates 


will recalculate the coordinate components of these elements: 


Oakland*.portBits. bounds Oakland*.portRect , 
Oakland*.visRgn 


All of the above items are always "in sync", so to speak: all 
calculations, comparisons, oF operations that seem right, work right. 
Notice that when the local coordinates of a grafPort are offset, the 
visRgn of that port is offset also, but the clipRgn is not. A good way 
to think of it is that if a document is being shown inside a grafPort, 
_-the document “sticks” to the coordinate systemyPind the port’s 
structure “sticks” to the screenp S$ rolling a document upwards inside 
its port involves. kaeping fali_the documents stuff {(like the clipRen) 
at the same pSsition, while ail the port’s stuff (like its 
portBits.bounds, portRect, and viskgn) is moved downwards. "he the top 
left corner of portBits.bounds is'fixed, moving its éory inates down 
looks like you”re moving the (Toupieat up. . 
” rane 


( hand) : 

All drawing takes place within a grafPort and uses the 
local coordinates of that grafPort. If you are moving, - 
comparing, or otherwise dealing with mathematical items 
in different grafPorts (for example, finding the 
intersection of two regions in two different grafPorts), 
you must adjust to a common coordinate system before you 
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QuickDraw first determines what bits of the bitMap will be affected, 
and dues a bit-by-bit comparison based onj the mode (described in 
“Transfer Modes”, below). The resultant pits are stored into the 
bitMap. Se Ss 


( hand) 
The character drawing mode\should be 
srcOr, sreXor, or srcBic in 6 
characters not obliterate each other. 


The_next four fields control the appearance of the font: 

\italiciging yletterspacing, and shadowing. You can apply these either 
alone of in combination; however, combinations of modes usually look 
good only for large fonts. All parameters should be positive; never 
set any of these parameters less than zero! 


& Normal Characters 


SS eeinboldenaasharacters 


SS 
va) Halie. Characters 
oidened isalic characters 
Trace, Chariesara 
nit faalie Shadowed ChanrnneEars 


avin im others fants, 


tol 


Figure 12. Character Styles 


The bold parameter controls linear overstriking of characters: the 
character is repeatedly “printed” one bit to the right, the number of 
times specified by the bold field. 


- The slant parameter adds an italic slant to the characters. A slant of 
f produces characters whose verticals are perpendicular to the 

- baseline; a slant of 8 produces a nice amount of italic ng for a 
1~-point font. The number of dots of horizontal skew per vertical line 
is determined by this formula: 


skewdots 
Character bits above the baseline are skewed right; bits below the 


- baseline are skewed left. 
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: vauak- 
The extra parameter adds space after the character; the Newwed extra ~ ( 
space is ff. You can add extra space in order t dettereprea— a 
rma? 2h it’s also helpful to add extra oe 
shado aracters. 9 slanted characters are kerned, it’s not eemsmttey 
necessary to pive them extra space. 


brbdfacing 
( Character sHadowing, controlled by the shadow parameter, is like 


t s a hollow, outlined character rather than a solid 
one. Like » the shadow parameter controls the number of .- 
times the character is—overstruck"; reasonable values are 9, 1, 2, and 


j 


GENERAL DISCUSSION OF DRAWING 
Drawing occurs: 
- Always inside of a grafPort, with the port”s coordinate system; 


Usually with the grafPort’s pen (that is, pen location, size, and 
pattern); 


On the grafPort”s bitMap; and 


Always clipped to the intersection of the (portRect,/bitMap bounds, 
visible region, and clipping region. 


‘Three things can be drawn: lines, shapes, and characters. Shapes 
include rectangles, ovals, rounded-corner rectangles, and regions, all 


either (solid Jor framed (hollow). 


ines are defined by two points: the current pen location 
destination location. When drawing a line, QuickDrayf draws_ 
left corner of the pen along the mathematical trajectd 
current location to the destination. The pen hangs below and to the 
‘right of the trajectory. 


fi bho 
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Figure 13. Drawing Benes 


( hand) alas th dt 


No mathematical detent (such as the pen location) is 
ever affected by clipping; clipping only determines what 
appears where (eng 3 If you draw a line to a 
location outside of your BrafPort, the pen location will 
:i-~génal@ there; but only the portion of the line that is 


inside the poft will actually be drawn. This is true for 
all drawing procedures. 


can 


Simple shapes (rectangles, ovals, and rounded-corner rectangles) are 


defined by two corner points. The shapes always appear inside the 
mathematical rectangle defined by the two points. A region is defined 


in a more complex manner, but it too appears only within the rectangle 
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Drawing (Shapes 
Drawing Framed Shapes 


14. 
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and the vertical and horizontal thickness of the 


outline is determined by the pen size 
The pen mode defines how those bits are to be 
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acter drawing does not use the pnMode or pnPat, but it does use the 


In the case of framed shapes, the outline still appears within the 
The pen pattern is used to fill in the bits that are affected by the 


operations to the bits in the shape and the corresponding 


affected by directing QuickDraw to apply one of eight boo 
screen.) 


defining rectangle, 
drawing operation. 
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& 


/ to the right a distance equal to the width of the character. , No wrap 


or carriage return is perfor 


wim don 
mCG a 


utomatically. 


The method QuickDraw uses in placing characters is controlled by a mode 
parameter similar to the pen mode. 


“Transfer Modes", below. 


Clipping of characters is performed 


exactly the same manner as all other clipping in QuickDraw. 


Transfer Modes 


field 


bit in the item to be drawn, Quic 
the bit image,amik- performs one of 
the pair of bits, and stores the résu 


There are four basic operations: 


Iruty ny shape ob eoney 


the pnMode 


pear on the screen 


kDra inds the corresponding bit in 
(sixteen) Coolean teen 


tting bit into the bit image. 


Copy, OR, XOR, and BIC. 


For each 


Each of 


these has a variant in which the drawing bit is inverted before the 


operation is performed, giving eight operations. 
or drawing with a pattern; the 
bit imagéyonto another, giving sixteen operations in a 


defined 


at 
AN , 


av 


‘ 
FN 
3 


wy 


¥ 


by name as. a constant in Quic 


Transferring~a Source Bit Image (Xfe 


Gree 
Hoae 


notSrcCopy 
notSrcOr 


i notSreXor 


notSrcBic 


~ 


“\ 
\ 


“Paint” 
“Overlay” 
“Invert” 
“Erase” 


“Paint” 
“Overlay” 
“Invert” 
“Erase” 


Pa 


These eight are used 
re are another eight for transferfing one 


: : Bave: 


Each mode is 


n 


En 
ae ron hed un destinattory 


Action,for each bit in source: 


Ate piace, 


Force Black 
Force Black 
nvert 

ree White 


Force Black 
Leave Alone 


1 


gas Alone 
ave Alone 


' 


_If_Whiter 


White 
Alone 


Force 
Leave 
Leave 
Leave Alone 
Force 
Force 
Invert 
Force White 


White 


White— 


Alone: \, 


ween 


ye" 


Transferring a Pattern (Line, LineTo, Paint, Fram Bes, or fuk 


tele 
Mode 


patCopy 
patOr 
patXor 
patBic 


notPatCopy 
notPatOr 
notPatXor 
netPatBic 


“Erase; 


“Paint” 
“Over 
“Inv 


a 


t" 


ay” 


lack: 

For 

Force Black 
Invert 
Force White 


Force Black 
Leave Alone 
Leave Alone 
Leave Alone 


|. Action for each bit in pattern: 
i 


“Paint” 
“Overlay” 
“Invert” 


White: 


Force-wntte 


Leave Alone 
Leave Alone 
Leave Alone 


Force White 
Force White 
Invert 

Force White 


» 


arene 


AW 
we 


freee 


one of the patternfmodes; the chStyle.mode 
ere eect 


{ 
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DESCRIPTION OF QUICKDRAW PROCLDURES 


The following pages describe Gaet- function’and proceduré in QuickDraw, 

their parameters, and their operation. They are given in their Pascal 

form; instructions on how to make procedure and function calls from 
.\._ assembly language cae ae the calls. 


grafPort Procedures a— _— 
alae 2 Ge 
PROCEDURE InitGraf; 


Call once and only once at the beginning of your program to initialize 
QuickDraw. It initializes the QuickDra global variables: 


« Variable Type 
. © white Pattern swhite pattern 
* black Pattern All-black pattern 
\ gray Pattern 
. 1tGray Pattern pattern 
dkGray Pattern pattern 
arrow Cursor joe arrow cursor 
charNormal (ch Cro FONE Src0s mode, no extras 


screenBits _ B Cintosh screen, (9,6,384,256) 


mo othePort ~~” me NI = 
Nt renseve—_ “ROOLEAN Fase 


ee on. the. screen. 


0 
4 
iy \ 


. 
; v ew 
PROCEDURE OpenPort (gp: ()GrafPtr); 


Initializes the selected grafPort and makes it the current port (see 
SetPort). You must perform an OpenPort before using any grafPort. To 
use OpenPort, perform a NEW to create a GrafPtr and use this GrafPtr in 
the OpenPort call. 


These default values are set by OpenPort: 


Variable Type j Setting 

portBits BitMap ScreenBits (see InitGraf) 

portRect Rect ScreenBits.bounds (9,9%,384,256) 

visRgn** Region Rectangular, (%,9,384,256) 

clipRgn** Region Rectangular, (-36696,-36660, 360040, 36600) 
bkPat Pattern White 

chStyle CharStyle CharNormal 

pnLoc Point (9,9) 

pnSize Point (1,1) 

pnMode INTEGER patCopy ¢ ¥- 


pnPat Pattern - Brack. AD 
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The top left corner of the portRect remains at its same location; the 
width of the portRect is set to width, and the height of the portRect 
is set to height. In other words, PortSize moves the bottom right 

corner of the portRect to a position relative to the top left corner. 


PortSize does not (update )the clipRgn or the visRgn, nor does it affect 

the local coordinate system of the grafPort: it only changes its width 
and height. Remember that all drawing occurs only in the intersection 

of the portRect, the portBits.bounds, the visRgn, and the clipRgn. . 


PROCEDURE MovePortTo (leftGlobal,topGlobal: INTEGER); 
i 


Cote y tt 's 
Changes the position of the n the bitMap (read “on the 4 
screen” )Cwithout altering the local coordinaté system of the port ; 
THIS DOES NOT AFFECT THE SCREEN; it merely changes the location onthe ” 
screen at which drawing inside the port will appear. See, last HB abe & 


( hand) 
This procedure is normally called only by the Window 
Manager. 


leftGlobal and topGlobal set the distance between the corners of ee 
portBits.bounds and the new portRect. For example, ie wat 
, we 


a ae 
ieeenceeretind Asays SS ee pres der 


will move the top left corner of the portRect to the center of the 
screen (if portBits is the Macintosh screen) regardless of the local 
coordinate system. 


MovePortTo recalculate e coordinates of =p eR 
all other coordinates unchanged. 


PROCEDURE SetOrigin (h,v: INTEGER); 


~bhis changes the dinate system of the current grafPort.¢ THIS 
__DOES NOT AFFE T THE SCREEN;}it does, however, affect where_subsequent 
rawing and calculation 1 appear in the portcon the screen. It 


updates the coordinates of the portRect, the portBits.bounds, and the 
visRgn. All subsequent drawing and calculation commands will use the 
new coordinate system. 


The h and v parameters set the coordinates of the top left corner of 


the portRect. All other coordinates are calculated from this point. 
All relative distances among any (lesenesyie the porewi11 remain the 
same; only their absolute local coor “change. 
( hand) 

SetOrigin does not update the coordinates of the clipRgn 


or the pen; these items [s @ document, inside the ree 
port, phot, the port on the fe 


mel eee 
Baste Vaan 
HG wd , iss 
v fy Meek, NG 
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PROCEDURE SetVisRgn (rgn: RgnHandle); 


Declares the region whose handle is supplied in rgn to be the visible 
region of the current port. 


This procedure is normally called only by the Window Manager. —. 
( hand) 
Note that SetVisRgn does not make a copy of the object 
region; it merely saves the RgnHandle inte_—=~ 
grafPort.visRgn. Thus, any subsequent changes you make 


to rgn will also eae visible region of the port. 


Be careful never to disposefa 


egion that has been set as the visible 
region of a grafPortg, unless you are also disposingathe grafPort 
itself. 3 ag : 


PROCEDURE GetVisRgn (VAR rgn: RgnHandle); Wr 3 


Returns a pointer to the cusreat visible on is defined in the 
coordinate system of the grafPort; if you wish to use this region in 
another port, you must offset it (see “Coordinate Systems”). 


ww’ 
ts nthe eg 


PROCEDURE Setclipfes) (ren: RgnHandle); 


. region of the current You can set the clipping region to any 
arbitrary region, to aid you in drawing inside the grafPort. The 
default clipRgn is an arbitrarily large rectangle. 


Declares the region coors handle is supplied in rgn to be the ee 


( hand) L 
Note that SetClipRgn does not make a copy of the object S 
region; it merely saves the RgnHandle i a 
grafPort.clipRgn. Thus, any subsequent Changes you make 

to rgn will also affect thejclipping region of the port. 

Be careful never to siepontlQ ceeson that has been set as 

the clipping region \((}nlessi\You are disposing of the 

grafPort itsel 


PROCEDURE cerciigtsy rgn: RgnHandle); 


Returns a handle to the clipping region of the current grafPort. You 
can use this, for example, to get a handle to_use in a region operation 
such as XorRgn, Unionkgn,, OffsetRen sober 


On 


It is defined in the coordinate system of the GrafCPorty if you wish to 
use this region in another port, you must offset it (see the 
LocalToGlobal and GlobalToLocal calls). rv 


\y ane oe é soefer 


La 


‘ae 
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PROCEDURE ClipRect/(r: Rect); 

Sets the clipping |region of the current grafPort to a rectangle 
@quivalent to the \rectangle r. NOTE that this does not change the 
region handle, but affects’ the region itselfs in combination with ° 
SetClipkgn, this may produce unexpected side effects. For example, 


SsetChi pReatmyReg ten): | aca 


Aiasd crore} ms 
ClipRect(anyRect) ee 


will not only set the clipping region to anyRect, but will also chan 
myRegion to anyRect. thre ag ee Gite, CRO rare 
apie a eSD peeeiane ia —— po be ee 

bien es pee 


Shean on, wee. les 


siettiog ere sn eetss, : NA eee 


PROCEDURE BackPat (oats Pattern); Aes 

\ i . 
Sets the background pattern of the current grafPort to pat. The- 
background pattern is used raseRect, EraseOval, EraseRoundRect, 


raseRpn, and ScrollRect. ile Z 
rp 
nA. the 
yagi 


Cursor-Handling Procedures 


PROCEDURE SetCursor (crsr: Cursor); 


Sets the current cursor to the 16-by-16’ image in crsr. If the cursor 
is hidden, it remains hidden and will attain the new appearance when it 
is uncovered; if the cursor is already visible, it attains the new 
appearance immediately. 


The initial(cursor image, when a port is created, is visible on the 
screen as a north-northwest arrow. There is no way to 
retrieve the current cursor image. 


(are/ el wt 
PROCEDURE HideCursor; ~“Gi/"= Bitton ack le Nd ju 

0 ereator ) Wa 
Removes the cursor from the screen, restoring the a oe it. 
HideCursor also decrements a “cursor--level" variable, which keeps track 
of the number of times the cursor has been hidden to compensate for he 
nested calls to HideCursor and ShowCursor. Every call to HideCursor % 
should be balanced—by—a_subsequent ca alj_to ShowCursor. At 
initialization, the cursor is not Eases : ux is 

wu wr 


aa i a one Wet 
PROCEDURE ShowCursor; I 


ncrements the ™ 


So extra calls to ShowCursor dont hurt. 
should balance a previous call to HideCursor. 


iad ’ 
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QuickDraw low-level interrupt-driven routines link the cursor with the 
ROUSG position, so that if the cursor level is @ (visible), the cursor 
automatically follows the mouse. You don*“t need to do anything but a 
ShowCursor to have a cursor track the mouse. There is no way to 
"disconnect" the cursor from the mouse; you can’t force the cursor to a 
certain position, nor can you easily prevent the cursor from entering a 
certain area of the screen. 


If the cursor has been changed (with SetCursor) while hidden, 
ShowCursor presents the new cursor. 


The initial cursor state is a north-northwest arrow, not hidden. 


PROCEDURE CursorVis (visible: BOOLEAN); 


A general-purpose cursor showing and hiding procedure: CursorVis(TRUE) 
simply calls ShowCursor, and CursorVis( FALSE) calls HideCursor. — 


Pen and Drawing Procedures a oe 
The pen and drawing procedures the coordinate 
system of the current grafPort. Remember that each grafPort has its 
own pen; if you draw in one grafPort, change to another, and return to 
the first, the pen will have remained in the same location. 


.PROCEDURE PenSize (width,height: INTEGER); 


Sets the dimensions of the graphics pen in_the current _grafPort. All 
subsequent Line, LineTo, (aieRect , FraseOval FrameRoundReéett, and 
FrameRgn procedure calls in the same grafPort will usé ew pen 


dimensions. 


a , 
i 
If either of the pen dimensions ave set be ponsosttive sek the pen 
"assumes the dimensions and no drawing is performed. The current 
pen dimensions can be essed in the variable thePort*.pnSize, which 
is of type Point (it has components .h and .v}. For a discussion of 
~ how the pen draws, see the "General Discussion of Drawing” earlier in 
this document. 


PROCEDURE GetPen (VAR pt: Point); 


Returns the current pen location, in the local coordinates of the 
current grafPort. 


( eye) 
If the coordinate system has been changed with SetOrigin 
since the last pen motion, the pen will not be in the 
same location on the screen. The pen “sticks" 
document: moving the document 
SetOrigin carries the pen with it into a new location in 
the grafPort. It will, however, be in the same location 
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relative to the coordinates of other items. 


PROCEDURE GetPenState (VAR pnState: PenState); 


Saves the pen location, size, and pattern into a storage variable, to 
be restored later with SetPenState (below). This is useful when 
calling short subroutines that operate in the current port but must 
change the graphics pen: each such procedure can save the pen’s state 
when it’s called, do whatever it needs to do, and restore the previous 
pen state immediately before returning. 


The PenState data type is not really useful for anything except saving 
the pen’s state. , 


PROCEDURE SetPenState (pnState: PenState); 
Sets the pen’s location, size, and pattern in the current grafPort to 
the values stored in pnState. This is usually called at the end of a 

- procedure that has altered the pen parameters and wants to restore them 
to their state at the beginning of the procedure (see GetPenState, 
above). 


PROCEDURE PenMode (mode: INTEGER); onPa 


Sets the transfer mode through which the? is transferred onto the 


Pimap. The mode may be any one of the patte acca GjJnasocciaenet 


patCopy patXor notPatCopy notPatXor 
pator patBic notPatOr ~~; hotPatBic bs 


ee ee 


f ds /. ec ae 7 
If the mode is one of end deme paedies, 5 (or a ce ), no 


drawing is performed. The current pen mode c be obtainedas an 
integer in the variable thePort*.pnMode. The initial pen mode is 
patCopy, in which the pen pattern is copied directly to the bitMap. 


ae 


PROCEDURE PenPat (pat: Pattern); 


Sets Leer ee een that is used by the pen in this grafPort. 

Standard patterns are defined for White, Black, Gray, LtGray, and 

DkGray; the initial pnPat is Black. The current pen pattern can be 

obtained in the variable thePort*.pnPat, and this value can be assigned 
- (but not compared!) to any other variable of type Pattern. 


PROCEDURE PenNormal; gan ov flow 


) 
Resets the intial state of the pen in this grafPort(, 


PnSize (1,1) 
PnMode patCopy 
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- t- 
PnPat Black ‘ \ \y a ae 
, t J 
yw a 


The pen location is not changed. 


PROCEDURE MoveTo (h,v: INTEGER); 


Moves the pen to location (h,v) in the local coordinates of the current 
grafPort. No drawing is performed. 


PROCEDURE Move (dh,dv: INTEGER); 


Moves the pen a distance dh horizontally and a distance dv vertically 
from its previous location. The positive directions are down and 
right. No drawing is performed. 


2 
wy 


\© PROCEDURE LineTo (h,v: INTEGER); 


', the trajectory of ,the new line is 
mathematically “added to the region’s boundary. ne 7 
(le 


AN 
CW 


/ 1%) FEO a, iehed cel 
Draws a line_a:digtance dh otizontal y and a distance dv Vertically 
from it { The positive directions a down and 


right. 
line. 


If a region is open and being formed, the trajectory of the new line is 
pa rieusceey added to the region’s boundary. 


Chardcter~Drawing Procedures 


Each grafPort has its own character style, and all these procedures 
deal with) the character style of the current ae io 


“ the cay aa 
PROCEDURE DrawChar (ch: CHAR); ane 


Places the selected character to the right of the pen location, and 
advances the pen the width of the character. If the character is not 
in the font, the font”s "missing symbol" will be drawn; if the font’s 
“missing symbol" is itself missing, expect a crash (in this incarnation 
of QuickDraw). 
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PROCEDURE DrawString (s: Str255); 


Performs co lsecutive calls to DrawChar for each character in the 
supplied sins the string is placed beginning at the current pen 
location shd extending right. No formatting (carriage returns, line 
feeds, és) is performed by QuickDraw. The pen location ends up to the 


right he last character in the string. 


( eye) 
If the string of characters extends beyond the clipping 
boundaries of the rv Wael grafPort, clipping will be 
performed as norma dy ut the pen location will remain to 
the right of the la character completely or partially p hore 
drawn, not the last character in the string. This is the 
only exception to the rule that clipping never affects y. pie 


the pen location. sii f fist AA 7 Tes a ys jae 


PROCEDURE DrawText (textBuf: WordPtr; firstByte,byteCount: INTEGER); 
War 

Draws text from an arbitrary structure in memory specified by textBuf, 
starting, firstByte bytes into the structure and continuing for 
byteCount bytes, and draws them on the screen in a string. The string 
is placed beginning at the current pen location and extending right. 
No formatting (carriage returns, line feeds, is performed by 
QuickDraw. The pen location ends up to the ght of the last character 
in the string (but see the warning for DrawString, above). 


The textBuf parameter, although of type WordPt is really a byte 
pointer; it may be an odd value to pmotee at(eitherybyte ina word. >) 
Se ease soe 


FUNCTION CharWidth (ch: CHAR): INTEGER; «2 

fa 
Returns the width of the given character; ie ae value is added to 
the pen horizontal coordinate whenever the specified character is’ 
drawn. The CharWidth includes the effects of the extra space 
parameter. 


FUNCTION StringWidth (s: Str255): INTEGER; 


Returns the width of the given text string; this same value is added to 
the pen horizontal coordinate whenever the specified string is drawn. 
The StringWidth includes the effects of the extra space parameter; if 
you change this parameter before actually drawing the string, your 
width will not be accurate. 


( eye) 
StringWidth and TextWidth always return the true length 
of the string as it would be drawn, regardless of 
clipping. But the actual difference between the 
beginning and ending pen locations may be affected by 
clipping (see DrawString and DrawText, above): in such 
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cases, the distance the pen moves while drawing the 
string is not the same as the width as piven by 
StringWidth or TextWidth. 


FUNCTION TextWidth (textBuf: WordPtr; firstByte,byteCount: INTEGER): 


INTEGER; h 
oh Ys 
Returns the width of the bend kt f"Smen arbitrary structure in - 


memory specified by textBuf, starting firstByte bytes into the 
structure and continuing for byteCount bytes. The TextWidth includes 
the effects of the extra space parameter; if you change this parameter 
before actually drawing the text, your width will not be accurate. 
(See also the warning for StringWidth, above). 


The textBuf parameter, although of type WordPtr, is really a byte 
pointer; it may be an odd value to point at either byte in a word. 


PROCEDURE SetChar (chS: CharStyle); 2) 


a 


Sets the Grepared) chS to be the character style of the current 
grafPort. You must initialize all fields of a CharStyle Hfore € 
installing it with SetChar. Calling SetChar(charNormal) will restore 
‘the default character font. 


After calling SetChar, all previously calcuated character, string, and 
text widths may become invalid due to a new font or extra space 
parameter. 


The current character style may be retrieved from the variable 
thePort*.chStyle. 


Calculations with Rectangles 


a“ 
( hand) ; 
Calculation procedures are independent of the current 
coordinate systems; a calculation will operate the same 
regardless of which grafPort is éctiv9. 


PROCEDURE SetRect (VAR r: Rect; left,top,right,bottom: INTEGER); 


Utility to assign four boundary coordinates to a rectangle. The result 
is a rectangle with coordinates (left,top,right, bottom). tut 


a | (onl erent 
ied oe is Supplied to help you shorten your 3 if you 


want), more readable ° at the expense of length, you can assign 
integers (or points) directly into the rectangle*s fields. There-is no 
significant code size or execution speed advantage to either method; 
one’s just easier to write, and the other’s easier to read. 
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PROCEDURE OffsetRect (VAR r: Rect; dh,dv: INTEGER); 


“Moves" the coordinates of a rectangle a distance dh horizontally and a 

distance dv vertically; positive directions are right and down. The 

rectangle retains its shape and size; only its coordinate noes tone A 
Ee eae eee 


altered. 
ad 


PROCEDURE InsetRect (VAR r: Rect; dh,dv: INTEGER); 

Aw 
Shrinks or a rectangle. The top and bottom are moved towards the 
center by the amount specified in dv; the left and right sides are 
moved in by the amount in dh. The effect is to alter the size by 2*dh 
horizontally and 2*dv vertically, with the rectangle remaining centered 
in the same place on the coordinate plane. If dh or dv is negative, 
the appropriate pair of sides is moved outwards instead of inwards. 


If either the resultant width or height becomes less than 1, the 
“rectangle is set to the null rectangle ($,9,0,9). 


FUNCTION SectRect (srcRectA,srcRectB: Rect; VAR dstRect: Rect): 
BOOLEAN; 


Calculates the rectangle that is the intersection of the two input 
rectangles, and returns TRUE if they indeed intersect and FALSE if they 
do not. Rectangles that “touch” at a line or a point are not 

’ consideted intersecting, because their intersection rectangle (really, 
in this case, an intersection line or point) does not enclose any bits 
on the tMap. 


If the rectangles do not intersect, the destination rectangle is set to 
(9,6,9,0). SectRect works correctly even if one of the source 


rectangles is ee destination. 
ey aba 
( hand) 4) Le eA. 
If the recta 2 appre ate iy o eekoeaee es 
grafPorts,} their mathematical nreysection (ao kbentaees 
SectRect) may be different Slug LET ate physical 
intersection on the screen. To adjust the points of a 
rectangle into another port”s coordinate system, see the 
LocalToGlobal and GlobalToLocal calls. 
Sica eT 


—* 


FUNCTION PtInRect (pt: Point; r: Rect): BOOLEAN; entity ab 


Determines if the pixel below and to the right of the givenkpoint is / 4 
enclosed in the given rectangle, and returns TRUE if so FALSE if ye 
not. (The chosen pixel is the one that would be are by a Linex¢, 0) / 


at the current pen location with a pen size of.(1,1 Both the 
and the rectangle must be in the same coordinate a ; 
: ae \e 


ae velo?) 
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PROCEDURE PaintRect (rs: Rect); 


Paints the specified rectangle with the pen pattern and mod The 
rectangle on the bitMap is filled with the pnPat, according to the 
transfer mode specified by pnMode. The pen Seated at its original - 
location. P 


PROCEDURE FrameRect (r: Rect); 

Draws a hollow outline with the pen pattern, mode, and size just inside 
the specified rectangle. The outline is as wide as the pen width and 
as tall as the pen height. The outline on the bitMap is filled with ~ 
the pnPat, according to the transfer mode specified by pnMode. The pen 
remains at its original location. 

If a region is open and being formed, the outside outline of the new 
rectangle is mathematically added to the region”s boundary. 


PROCEDURE EraseReet (r: Rect); 


Paints the specified rectangle with the background pattern bkPat. The 


pnPat and pnMode are ignored) fhe pen remains at its original location. 
; ; 


PROCEDURE InvertRect (r: Rect); 


The bits enclosed by the specified rectangle are inverted: every white 
bit becomes black and every black bit becomes white. The pnPat, 
pnMode, and bkPat are all ignoredg fhe pen remains at its original 
location. ’ = 7 


PROCEDURE FillRect (r: Rect;. pat: Pattern); 


Paints the specified rectangle with e given pattern. The pnPat, 
pnMode, and bkPat are all ignoredj Ahe pen remains at its original 
location. rt mae ee 


PROCEDURE ScrollRect (dstRect: Rect; dh,dv: INTEGER; \updateRgn: 
rgnHandle); 


ScrollRect alters only those bits inside the dstRect, the visRgn, the 
clipRgn, the portRect, and the portBits.bounds. The bits in the - 
intersection of all those get shifted a distance of dh horizontally and 
a distance of dv vertically; positive directions are right and down. 
Bits that are shifted out of the scroll area are lost; they are neither 
placed outside the area nor saved (of £) The background pattern bkPat is 
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\ 


( scrolled into} the space created by the scroll. In addition, Updareken. Jeet athe 
“Ts change Fo contain all bits that werc et ‘in aa 
e ; EE See a es 


Before SerouRect After ScrolikucrtdstRect,-10,5...) 


st 


Races: of 
Quick Draw... 


dst Rect 
Upacergn 


Figure 16. Scrolling 


rRect (srcBits,dstBits: ie srcRect, dstRect: Rect; 
- Sea pat:Pattern 
aes ; : 


\ The crangter hay be 

transfer modes. The transfer is always 

clipped to the boundary pee of the \destination bitMap, and, if the 
destination bitMap is thé current grafPort” s cet, too the transfer is 


clipped inside the clipkgn, visRen, \and portRect, too ye 
\ 
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Pattem Destinasion RitMap. 


ye Figure 17. Operation of XferRect 
The DétRect coordinates are in terms of the dstBits.bounds coordinate 
system; the SrcRect coordinates are in terms of the srcBit 
coordinates. When ccepying from the source to the destination, the top 
left corner of the source rectangle is aligned with the top left corner 
of the destination rectangle; the size of the source rectangle is 
ignored. 

ak 
In the sources 6m transfer modes, each bit of the source is 
transferred to the destination according to the rules of that mode, and 
the pattern is ignored (we suggest you set it to white). The eight 
Source ware modes are as follows: 


srcCopy srcXor notSrcCopy notSrcexor 
srcOr srcBic notSrcOr notSrcBic 


In the pattern~sedmp transfer modes, the specified pattern is 
7 trans (ere into the destination rectangle according to the chosen mode. 
The soufce bitMap and source rectangle are not used; we suggest you set 
these to the Me rre wares bitMap and destination rectangle. : peti 
patCopy . patXor notPatCopy notPatXor + 
pator patBic notPatOr notPatBic 


These ys modes are useful for filling a rectangle that is outside 
“Qref the current grafPort. For filling a rectangle inside the current 
grafPort, however, the FillRect procedure is much easier to use. 


ne 4 Haft vey hea eing > 


Graphidal}] Operations on Ovals 
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PROCEDURE PaintOval (r: Rect); 


Paints an oval just inside the specified rectangle with the pen pattern 
and mode. The oval on the bitMap is filled with the pnPat, according 
to the transfer mode specified by pniiode. The pen remains at its 
original location. 


PROCEDURE FrameOval (r: Rect); 


Draws a hollow outline with the pen pattern, mode, and size just inside 
the oval that fits inside the specified rectangle. The outline is as 
wide as the pen width and as tall_as the pen height. The outline on 
the bitMap is filled with the pnPat, according to the transfer mode 
specified by pnMode. The pen remains at its original location. 


If a region is open and being formed, the outside outline of the new 
oval is (yathemat ically added to the region’s boundary. - 
PROCEDURE EraseOval (r: Rect); 

Paints an oval just inside the specified rectangle with the background 
pattern bkPat. The pnPat and pnMode are ignored; the pen remains at 
its original location. 

PROCEDURE InvertOval (r: Rect); 

The bits enclosed by an oval just inside the specified rectangle are 
inverted: every white bit becomes black and every black bit becomes 
white. The pnPat, pnMode, and bkPat are all ignored; the pen remains 
at its original location. 

PROCEDURE FillOval (r: Rect; pat: Pattern); 

Paints an oval just inside the specified rectangle with the given 


pattern. The pnPat, pnMode, and bkPat are all ignored; the pen remains 
at its original location. | 
Q 


Operations on Rounded-Corner Rectangles 


PROCEDURE PaintRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 


Paints the specified rounded-corner rectangle with the pen pattern and 
mode. The rounded-corner rectangle on the bitMap is filled with the 
pnPat, according to the transfer mode specified-by pnMode. The pen 
remains at its original location. OvalWidth and ovalHeight specify the 
diameters of curvature for the corners. 
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aval Width ovalHeight 


Figure 18. Rounded-Corner Rectangles 


PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 


Draws a hollow outline with the pen pattern, mode, and size just inside 
the specified rounded-corner rectangle. The wide as the 


pen width and as te7 3s the pen hetght: The outline on the bitMap is 
filled with the pnPat, according to the transfer mode specified by 
pnMode. The pen remains at its original location. OvalWidth and 
ovalHeight specify the diameters of curvature for the corners. 


If a region is open and being formed, the outside outline of the new 
rounded-corner rectangle is mathematically added to the region’s 
boundary. 


PROCEDURE EraseRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 


Paints the specified rounded-corner rectangle with the background 
pattern bkPat. The pnPat and pnMode are ignored; the pen remains at 
its original location. OvalWidth and ovalHeight specify the diameters 
of curvature for the corners. 


PROCEDURE InvertRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 


The bits enclosed by the specified rounded-corner rectangle are 
inverted: every white bit becomes black and every black bit becomes 
white. The pnPat, pnMode, and bkPat are all ignored; the pen remains 
at its original location. OvalWidth and ovalHeight specify the 
diameters of curvature for the corners. 
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PROCEDURE FillRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER; pat: 
Pattern); 


Paints the specified rounded-corner rectangle with the given pattern. 
The pnPat, pnMode, and bkPat are all ignored; the pen remains at its 
original location. OvalWidth and ovalHeight specify the diameters of 
curvature for the corners. 


Calculations with Regions 


Ffuinchon 
FUNCTION NewRgn: RgnHandle; 
Creates space for a newydynamic, variable-size region, initializes it 
to the empty region, and returns a handle to the new region. Only this 


creates new regions; all other procedures just alter the size 
and shape of regions you create. 7 


Never refer to a region without using its handle; regions are too big 
and awkward to be carried around any other way. 


( eye) 


You must call NewRgn to initialize a region’s handle 
eTeul that handle can be used in any region drawi 


culation procedure. 


PROCEDURE DisposeRgn (rgn: RgnHandle); 


Deallocates space for the region whose handle is supplied, and returns 
the memory used by the region to the free memory pool. Use this only 
after you are completely through with a temporary region. 


( eye) Za 
NEVER use a region once you have deallocated it, or you “7 


will risk being hung by dangling pointers! / Bewate of 

—-SetClipRgn and SetViskgn; they don“t duplicate the 
region, they only make a copy of the handle. If you 
deallocate a region that Gor madiqusly satis be your 
clipRgn, your clipping goes away and very strange things 
will occurf). 


PROCEDURE CopyRgn (srcRgn,dstRgn: RgnHandle); 
Beg ee 

Copies the mathematical structure of srcRgn into dstRgn; i.e. it makes 

a duplicate copy of srcRgn. Once this is done, srcRgn may be altered 

(even disposed of) without affecting dstRgn. 
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PKOCEDURE SetRectkgn (rgn: RgnHandle; Lene POD EMEC g nO eOn: INTEGER) 3 


Destroys the previous Gata structuré) of rgn, then sets the new 
structure to the rectangle specified by left, top, right, and bottom. 


This is a good way to obtain a rectangular region, and also to seta 
region to the null region (9,9,0,9)- 


If the rectangle specified is not rectangular (i.e. left>=right or 
top>=bottom), the region is set to the null region. 


PROCEDURE RectRgn (rgn: RgnHandle; r: Rect); 


Destroys the previous data structure of rgn, then sets the new 
structure to the rectangle specified by r. This is operationally 
synonymous with SetRectRg p he input rectangle is defined by a 
rectangle, not four bourdary coordinate 


PROCEDURE OpenRgn; fiw ai a 

OpenRgn tell uickDraw to sinocaty/eemrorer space af start saving 

line segments)and framed shapes later be process as a region 
nition. 


The global BOOLEAN variable RgnSave indicates whether a 


region is open; flipping RgnSave FALSE disables the collection of lines 
and frames, and restoring RgnSave TRUE resumes the region definition. 


All Line, LineTo, \framéRéct, FrameOval, FrameRoun 
procedure calls whilé on {fs open affect the outline of the 


region. Only the line endpoints and shape boundaries affect the region 
definition, not the pen mode, pattern, size, or location. In fact, 

it’s best to set the penSize to (f%,%) before drawing a region: ecthe 
pen hangs below and to the right on a line, drawing lines with even the 
smallest pen will change bits that do not mathematically belong to the 
region. “ 


The outline of a region is mathematically defined and infinitely thin, 
and separates the bitMap into two groups of bits: those within the 
region and those outside it. A region should consist of one or more 
closed loops. Each frame itself constitutes a loop; any lines drawn 
with Line or LineTo should connect with each other or with a frame. 
Even though the on-screen presentation of a region is clipped to the 
portRect, etc., the creation of a region is not; you can define a 
region anywhere on the coordinate plane with complete disregard for the 
location of various grafPort entities on that plane. 


( eye) 
Do not perform an OpenRgn while another region is already 
open. All open regions but the most recent will behave 
strangely. 
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PROCEDURE CloseRgen (dstRgn: RgnHandle); 


Stops the collection of endpoints and outlines, organizes them into a 
region definition, and saves the resulting region into the region 
indicated by dstRgn. You should perform one and only one CloseRgn for 
every OpenRgn. 


Here’s an example of how to create and open a region, define a Se aed, ) 
shape, close the region, and draw it: ye oe 


be fu J ane ve \ 
Barbell := NewRgn; 7 poke a new region} ~~ 
PenSize($,8); don*t draw it on the seceeal 
OpenRgn; {begin collecting stuff} 
SetRect(tempRect, 29, 26,39,50); faraw’the left weight} 
\“FrameOval(tempRect); 
SetRect(tempRect, 3%, 30,80, 48); f4raw’the bar} 
~FrameRect(tempRect)3 , ; 
SetRect(tempRect, 8, eae ies right weight} 
~~ FrameOval(tempRect)3 
CloseRgn( Barbell); pore re done; save in barbell} 
FillRgn( Barbell, Black); — ry” pois it! } 7 
DisposeRgn( Barbell) {we don*t need you anymore...} 


PROCEDURE OffsetRgen (rgn: RgnHandle; dh,dv: INTEGER); 
Mathematically moves the region a distance of dh horizontally and dv 


vertically; positive directions are right and down. The region retains 
its size and shape; it merely is moved on the coordinate plane. 


PROCEDURE InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 


Shrinks or ‘cows the region. All points on the region boundary are 
moved inwards a distance of dv vertically and dh horizontally; if dh or 
dv is negative, the points are moved outwards in that direction. 
InsetRgn leaves the region “centered” at the same position, but moves 
the outline in (for positive values) or out (for negative values). 
InsetRgn of a rectangular region works just like InsetRect (see). 


PROCEDURE SectRgn (sreRgnA,srcRgnB,dstRgn: RgnHandle); 


Calculates the intersection of two regions and places the intersection 
in a third region. THIS DOES NOT CREATE THE DESTINATION REGION: you 
must use NewRgn to create the dstRgn before you call SectRgn. The 
destRgen can be one of the source regions, if desired. 


If the regions do not intersect, or one of the regions is the empty 
region, the destination is set to the empty region, which you can test 
with the EmptyRgn function. 
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If the regions were defined in different grafPorts, the mathematical 
intersection (from SectRgn) way not correspond to their physical 
intersection on the screen. ‘To adjust a region into another port’s 
coordinate system, see the LocalToGlobal and GlobalToLocal calls. 


PROCEDURE UnionRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 


Calculates the union of two regions and places the union in a third 
region. THIS DOES NOT CREATE THE DESTINATION REGION: you must use 
NewRgn to create the dstRgn b ggre you call UnionRgn. The destRgn can 
be one of the source regions, If desired. 


If both regions are empty, the destination is set to the empty region, 
which you can test with the EmptyRgn function. 


If the regions were defined in different grafPorts, the mathematical 
union (from UnionRgn) may not correspond to their physical union on the 
screen. To adjust a region into another ports coordinate system, see 
the LocalToGlobal and GlobalToLocal calls. 


PROCEDURE DiffRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle) ; 


Subtracts srcRgnB from srcRgnA and places the difference in a third 
region. THIS DOES NOT CREATE THE DESTINATION REGION: you must use 
NewRgn to create the dstRgn bite you call DiffRgn. The destRgn can 
be one of the source regions, Wf desired. 


If the first source region is the empty region, the destination is set 
to the empty region, which you can test with the EmptyRgn function. 


If the regions were defined in different grafPorts, the mathematical 
difference (from DiffRgn) may not correspond to their physical 
difference on the screen. To adjust a region into another port”s 

“ coordinate system, see the LocalToGlobal and GlobalToLocal calks. 


PROCEDURE XorRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 


Calculates the difference between the union and the intersection of two 
regions and places the result in a third region. THIS DOES NOT CREATE 
THE DESTINATION REGION: you must use NewRgn to create the dstRgn 
begore you call XorRgn. The destRgn can be one of the source regions, 
if desired. 


If the regions are coincident, the destination is set to the empty 
region, which you can test with the EmptyRgn function. 


If the regions were defined in different grafPorts, the mathematical 
Xor (from XorRgn) may not correspond to their physical Xor on the 


screen. To adjust a region into another port’s coordinate system, see 
the LocalToGlobal and GlobalToLocal calls. 
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Task Rare 


Pattem Destination BirMap 


Figure 19. Operation of XferRgn 


The DstRect and MaskRgn coordinates are in terms of the dstBits.bounds 
coordinate system; the SrcRect coordinates are in terms of the 
srcBits.bounds coordinates. When copying from the source to the 
destination, the top left corner of the source rectangle is aligned 
with the top left corner of the destination rectangle; the size of the 
source rectangle is ignored. 


In the sourcesusiwge transfer modes, each bit of the source is 
transferred to the destination according to the rules of the mode. The 
pat parameter is ignored; we recommend you set it to white. The 
source~ysétap—modes are as follows: 


srcCopy srcXor notSrcCopy notSrexor 
srcOr srcBic notSrcOr notSrceBic 
. & 


In the patternssmite transfer modes, the specified pattern is 
transfered into the destination rectangle according to the chosen mode. 


The source bitMap and rectangle are not used; we suggest you set these 
to the destination bitMap and rectangle. 


patCopy patXor notPatCopy notPatXor 
pator patBic notPatOr notPatBic 


These transfer modes are useful for filling a region that is in some 
other GrafPort. 


Miscellaneous Utilities 
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FUNCTION Random: INTEGER; 


Returns a 16-bit signed integer, uniformly distributed pseudo-random. 
Ff 


i 
f 


FUNCTION GetPixel (h,v: INTEGER): BOOLEAN; \ 


Peeks at a single bit in memory (perhaps a pixel) and returns TRUE if 

: the(dot )is black and FALSE if the dot is white. The selected pixel-is 
the one immediately below and to the right of the point whose 
coordinates are given in h and v; these points are in the local 
coordinates of the current grafPort. There is no guarantee that the 
pixel actually belongs to the port, however, it may have been drawn by 
a port overlapping the current one. To see if the point indeed belongs 
to the current, port, perform a PtInRgn(pt,thePort~.visRgn). 


PROCEDURE AddPt (sre: Point; VAR dst: Point); i 


Adds the first point to the second, returns the sum in the second 
point. 


PROCEDURE SubPt (sre: Point; VAR dst: Point); 


Subtracts the first point from the second, returns the result in the 
second point. 


PROCEDURE SetPt (VAR pt: Point; h,v: INTEGER); 


Assigns two integer coordinates to a variable of type point. 


PROCEDURE LocalToGlobal (VAR pt: Point); 


= 


Converts the given point from the current grafPort’s local coordinate 
system into a global coordinate system with the origin (9,9) at the top 
left corner of the port’s bitMap (such as the screen). This global 
point can then be compared to other global points, or be changed into 
the local coordinates of another grafPort. For example, if the 
rectangle ballRect is defined in the gamePort grafPort, and you want to 
use that rectangle in the selectPort grafPort, you would calculate the 
ball’s coordinates like this: 


SetPort(gamePort); { start in origin port} 

SelectBall := ballRect; {make a copy to be moved} 
LocalToGlobal(SelectBall.topLeft); { put both corners into } 
LocalToGlobal(SelectBall.botRight); { global coordinates } 


SetPort(selectPort); { switch to destination port } 
GlobalToLocal(SelectBall.topLeft); { put both corners into J 
GlobalToLocal(Selectball.botRight); { these local coordinates } 
FillOval(SelectBall,BallColor,8,8); { Now you have the ball! } 


2/17/81 Espinosa / QUICK. DRAW/QUIKDRAW .6 


QuickDraw Programmer's Guide * 15 February 1982 Page 0053 of 0064 


Apple Macintosh Early Technical Information * Inside Macintosh 


DESCRIPTION OF QUICKDRAW PROCEDURES 53 


You can also convert rectangles and regions into global coordinates 
without performing a LocalToGlobal call for each point. Simply perform 
LocalToGlobal for one point (for example, the top left corner of the 
region’s bounding box), then use OffsetRect or OffsetRgn to move the 
rest of the object the distance of displacement: 


CopyRgen(myRgn, tempRgn); 

tempPoint := tempRgn**.rgnBBox.topLeft; 
LocalToGlobal(tempPoint); 

OffsetRgn(tempRgn, tempPoint.h, tempPoint.v) 


PROCEDURE GlobalToLocal 


Takes a point expressed in global coordinates (with the top left corner 
of the bitMap as coordinate ($%,f)) and converts it into the local 
coordinates of the current grafPort... The global point can be obtained 
with the LocalToGlobal call (see above). 


You can convert global-coordinate rectangles and regions into local 
coordinates without performing a GlobalToLocal call for each point. 
Simply perform GlobalToLocal for one point (for example, the top left 
corner of the region’s bounding box), then use OffsetRect or OffsetRgn 
to move the rest of the object the distance of displacement: 


SetPort(MyNewPort); 

tempPoint := globRgn**.rgnBBox.topLeft; 
GlobalToLocal(tempPoint); 

OffsetRgn(globRgn, -tempPoint.h, -tempPoint.v) 


PROCEDURE StuffHex (thingptr: WordPtr; s:Str255)3 


Pokes bits (expressed as a string of hexadecimal.digits) into any. data 
structure. This is a good way to create cursors, patterns, or bit 
images to be “stamped” onto the screen with XferRect. For example, 


StuffHex(@stripes, ~$1926498192040890" ) 


places a striped pattern into the pattern variable stripes. Beware; 
there is no range checking on the size of the destination variable; 
it’s easy to overrun the variable and something if you don’t know 
what you”re doing. 


USING QUICKDRAW FROM ASSEMBLY LANGUAGE 


All Macintosh User Interface ToolBox routines can be called from 
assembly-language programs as well as from Pascal. When you write an 
assembly-language program to use these routines, though, you must 
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emulate Pascal”s parameter passing and variable transfer protocols. 


The remainder of this section discusses how to use the QuickDraw 
constants, global variables, data types, procedures and functions from 
assembly language. 


The primary aid to assembly-language programmers is a file named 
GRAFEQU.TEXT. If you .INCLUDE this file when you assemble your 
program, all the QuickDraw constants, offsets to locations of global 
variables, and offsets into the fields of structured types will be 
available in symbolic form to your programs. 


Constants : 
QuickDraw constants are stored in the GRAFEQU.TEXT file, and you can 
use the constant values symbolically. For example, if you”ve loaded 
the effective address of the thePort*™.chStyle.mode field into address 
register A2, you can set that field to the sreXor mode. with this. 
statements: 


MOVE.W #SRCXOR,(A2) 


The only constants defined at this point are the sixteen transfer 
modes. 


Data Types ; 
Pascal’s strong typing ability lets you write Pascal programs without 
really considering the size of a variable. But in assembly language, 
you must keep track of the size of every variable. The sizes of the 
standard Pascal data types are as follows: 


Type Size 

INTEGER Word bytes) 
LONGINT Long bytes) 
Pointer Long bytes) 
BOOLEAN Word bytes) 
REAL Long bytes) 
CHAR . Word bytes) _ 


INTEGERs and LONGINTs are in twos complement form; BOOLEANS have their 
boolean value in bit 8 of the word (the low-order bit of the byte at 
the same location); CHARs are stored in the high-order byte of the © 
word; and REALs are in the KCS standard format. 


QuickDraw simple data types are constructed out of these fundamental 
types. 


Type Size 

WordPtr Long (4 bytes) 
str255 Page (256 bytes) 
Pattern 8 bytes 
Bits16 32 bytes 
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Other data types are constructed as records of variables of the above 
types. The size of such a type is the sum of the sizes of all the 
fields in the record; the fields appear in the variable with the first 
field in the lowest address. For example, the data type BitMap, which 
is defined like this: 


BitMap = RECORD 
baseAddr: WordPtr; 
rowBytes: INTEGER; 
bounds: Rect 
END 4 


would be arranged in memory as seven words: a long for the baseAddr, a 
word for the rowBytes, and four words for the top, left, right, and 
bottom parts of the bounds rectangle. To assist you in referring to 
the fields inside a variable that has a structure like this, the 
GRAFEQU.TEXT file defines constants that you can use as offsets into 
the fields of a structured variable. For example, to move a bitMap’s 
rowBytes value into D3, you would execute the following instruction: 


MOVE.W MYBITMAP+ROWBYTES, D3 


Displacements are given in the GRAFEQU.TEXT file for all fields of all 
data types defined by QuickDraw.- 


3 To do double indveaceiony( (for example, to get at the top coordinate of 
a region’ s, bounding box), you perform an LEA indirectly to obtain the 


effective address from the handle: 


MOVE.L MYHANDLE,AlL Load handle into Al 
MOVE.L (Al),Al Use handle to get pointer 
MOVE.W RGNSIZE+TOP(A1),D3 Load value using pointer 


For regions (and all: other variable-length structures 
with handles), you must not move the pointer into a 
register once and just continue to use that pointer; you 
must do the double indirection each time. Every 
QuickDraw, ToolBox, or memory management call you make 
can possibly trigger a heap compaction that renders ail 
pointers to movable heap items (like regions) invalid. 
The handles will remain valid, but pointers you’ve 
obtained through handles can be rendered invalid at any 
subroutine call or trap in your program. 


Global Variables 
Global variables are stored in a special section of Macintosh low 
memory; register A5 always points to this section of memory. The_ 
GRAFEQU.TEXT file defines a constant GRAFGLOB that points to the 
beginning of the QuickDraw variables in this space, and other constants 
to point at the individual variables. To access one of the variables, 
just sum the constants and index off of A5. For example, if yo ve) are 
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preparing a bitMap record and you want that bitMap to share the same 
bit image as the screenBits global variable, you’d perform the 
following instruction: 


MOVE.L GRAFGLOB+SCREENBITS+BASEADDR(A5) ,MYBITMAP+BASEADDR 


Procedures and Functions 
To call a QuickDraw procedure or function, you must push all parameters 
to that function on the stack, then JSR to the function or cedure. 
When you link your program with QuickDraw, these JSRs are shaved to 
refer to the jump table in low RAM, so that a JSR into the le 
redirects you to the actual location of the procedure or function. 
After the procedure or function has unstacked all its parameters and 
performed its operation, it returns to you with the stack cleared. 


The only difficult part about. calling. .QuickDraw procedures and .. 
functions is stacking the parameters. You must follow some strict 
rules: 


Save all registers you wish to preserve before you begin pushing 
parameters. Any QuickDraw procedure can destroy the contents of 
the registers Af, Al, Df#, Dl, and D2, but the others are never 
altered. 


Push the parameters in the order that they appear in the Pascal 
procedural interface. 


For integers, booleans, and characters, push a word; for pointers, 
handles, long integers, and reals, push a long. 


For any structured variable longer than four (4) bytes, push a 
pointer to the variable. 


For all VAR parameters, regardless of size, push a pointer to the 
variable. 


When calling a function, FIRST push a null entry equal to the size 
of the function result, THEN push all other parameters. The 
result will be left on the stack after the function returns to 
you. 


This makes for a lengthy interface, but it also guarantees that you can 
mock up a Pascal version of your program, and when you later translate 
it into assembly code, it works the same. For example, the Pascal 
statement 


Blackness := GetPixel(5$,MousePos.v); 


would be written in assembly language like this: - 


CLR.W -(SP) : ; Save space for boolean result 
MOVE.W #32,-(SP) ; Push constant 5% (decimal) 
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MOVE.W MOUSEPOS+V,~(SP) 3; Push the value of MOUSEPOS.V 
JSR GETPIXEL 3 Call routine 
MOVE.W (SP)+,BLACKNESS 3 Fetch result from stack. 


This is a simple example, pushing and pulling word-long constants. 
Normally, you”11 be pushing more pointers, using the PEA (Push 
Effective Address) instruction: 


FillRoundRect (MyRect,1,thePort*.penSize.v,White); 


PEA MYRECT 3 Push pointer to MYRECT 
MOVE.W #1,~-(SP) 3; Push constant lL 
MOVE.W GRAFGLOB+THEPORT+PENSIZE+V(A5) ,-(SP) 

3 Push value of ThePort*.penSize.v 
PEA GRAFGLOB+WHITE(A5) 3; Push pointer to global var White 
JSR FILLROUNDRECT 3 Call the subroutine 


Beware that the horizontal and vertical. parts of a point do not appear 
in the same order in the data structure as they do in a procedure call! 
Even though you can move a point around with a MOVE.L instruction, you 
can”t push that point as a parameter to a procedure which requires two 
integer coordinates. For example, to call MoveTo with a point 
argument, you must do two separate pushes: 


MOVE.W MOUSEPOS+H,~-(SP) ; Push horizontal position 
MOVE.W MOUSEPOS+V,-(SP) — ; Push vertical position 
JSR MOVETO 


Just doing a MOVE.L MOUSEPOS,~-(SP) would transpose the vertical and 
horizontal results, and make MoveTo work funny. 


SUMMARY OF QUICKDRAW 

CONST srcCopy 
srcOr 
srcXor 
srcBic 
notSrcCopy 
notSrcOr 
notSrcXor 
notSrcBic 
patCopy 
pator 
patXor 
patBic 
notPatCopy 
notPatOr 
notPatXor 
notPatBic 


it 
a 


Destination 
Destination 
Destination 
Destination 
Destination 
Destination 
Destination 
Destination. 
Destination 
Destination 
Destination 
Destination 
Destination 
Destination 
Destination 
Destination 


Source } 


Source OR Destination } BIC’ 


Source XOR Destination } 
Source BIC Destination } 
NOT(Source) } 

NOT(Source) OR Destination } 
NOT(Source) XOR Destination } 
NOT(Source) BIC Destination } 
Pattern } 

Pattern OR Destination } 
Pattern XOR Destination } 
Pattern BIC Destination } 
NOT(Pattern) } 

NOT(Pattern) OR Destination } 
NOT(Pattern) XOR Destination } 
NOT(Pattern) BIC Destination } 


ro | 
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TYPE WordPtr = 
Str255 
Pattern = PACKED ARRAY[@..7] OF @.. 
Bitsl6 = ARRAY[{@%.-.15] OF INTEGER; 
VHSelect = (v,h);3 


Point = RECORD CASE INTEGER OF 


$: (vw: INTEGER; 
h: INTEGER); 


: ARRAY[VHSelect] OF INTEGER); 


Rect = RECORD CASE INTEGER OF 


@: (top: INTEGER; 
left: INTEGER; 
bottom: INTEGER; 
right: INTEGER) 3 


l: (topLeft: “Point; 
botRight: Point); 
END; 


BitMap = RECORD 
baseAddr: WordPtr; 
rowBytes: INTEGER; 
bounds: Rect; 
END; 


Cursor = RECORD 
data: Bits16; 
mask: Bits16; 
hotSpot: Point; 
END; 


CharStyle = RECORD 
fontPtr: Handle; 
mode: INTEGER; 
bold: INTEGER; 
slant: INTEGER; 
extra: INTEGER} 
shadow: INTEGER}; 
END; 


PenState = RECORD 
pnLoc : Point; 
pnSize Point; 
pnMode INTEGER; | 
pnPat : Pattern 
END; - 
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RgnHandle = “RenPtr; 
RenPctr = “Region; 
Region RECORD 
rgnSize: INTEGER; { rgnSize = 1% for rectangular 
rgnBBox?: Rect3 
{ more data if not rectangular 
END; 


GrafPtr “GrafPort; 

GrafPort RECORD 
portBits: BitMap; 
portRect: Rect; 
visRgn: RgnHandle; 
clipRgn: RgnHandle; 
bkPat: Pattern; 
chStyle: Charstyle; 
pnLoc: Point; 
pnSize: Point; 
pnMode: INTEGER; 
pnPat: Pattern; 

END; 


VAR thePort: GrafPtr; 
white, black,gray,1tGray,dkGray: Pattern; 
arrow: Cursor; 
grafError: INTEGER; 
grafDebug: BOOLEAN; 
screenBits: BitMap; 
charNormal: CharStyle; 
swapFont: ProcPtr; 
rgnSave: BOOLEAN; 


Housekeeping and GrafPort Procedures 
PROCEDURE InitGraf; 
PROCEDURE OpenPort (gp: GrafPtr);. 
PROCEDURE SetPort (gp: GrafPtr); 
PROCEDURE GetPort (VAR gp: GrafPtr); 
PROCEDURE SetPortBits(bm: BitMap); 
PROCEDURE PortSize (width,height: INTEGER); 
PROCEDURE MovePortTo (leftGlobal,topGlobal: INTEGER); 
PROCEDURE SetOrigin (h,v: INTEGER); 
PROCEDURE SetVisRgn (rgn: RgnHandle); 
PROCEDURE GetVisRgn (VAR rgn: RgnHandle)3; 
PROCEDURE SetClipRgn (rgn: RgnHandle); 
PROCEDURE GetClipRgn (VAR rgn: RgnHandle)3; 
PROCEDURE ClipRect (r: Rect); 
PROCEDURE BackPat (pat: Pattern); 
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Cursor Handling 
PROCEDURE SetCursor 
PROCEDURE HideCursor; 
PROCEDURE ShowCursor; 
PROCEDURE CursorVis 


(ersr: Cursor); 


(visible: BOOLEAN); 


Pen and Line Drawing 
PROCEDURE GetPen (VAR pt: Point); 
PROCEDURE GetPenState (VAR pnState: PenState); 
PROCEDURE SetPenState (pnState: PenState); 
PROCEDURE PenSize (width,height: INTEGER); 
PROCEDURE PenMode (mode: INTEGER); 
PROCEDURE PenPat (pat: Pattern); 
PROCEDURE PenNormal; 
PROCEDURE MoveTo 
PROCEDURE Move 
PROCEDURE LineTo 
PROCEDURE Line 


(h,v: INTEGER); 
(dh,dv: INTEGER); 
(h,v: INTEGER); 
(dh,dv: INTEGER); 


Character Drawing 
PROCEDURE DrawChar 
PROCEDURE DrawString 
PROCEDURE DrawText (textBuf: WordPtr; firstByte, byteCount: INTEGER); 
FUNCTION CharWidth (ch: CHAR): INTEGER; 

FUNCTION StringWidth (s: Str255): INTEGER; 
FUNCTION TextWidth (textBuf: WordPtr; firstByte,byteCount: INTEGER): INTEGER; 
PROCEDURE SetChar (chS: CharStyle); 


(ch: char); 
(s: Str255); 


Calculations with Rectangles 
PROCEDURE SetRect (VAR r: Rect; left,top,right,bottom: INTEGER); 
PROCEDURE OffsetRect (VAR r: Rect; dh,dv: INTEGER); 
PROCEDURE InsetRect (VAR r: Rect; dh,dv: INTEGER); 
FUNCTION SectRect (srcRectA, srcRectB: Rect; VAR dstRect: Rect): BOOLEAN; 
FUNCTION PtInRect (pt: Point; r: Rect): BOOLEAN; 


Scaphida) onceadinae on Rectangles 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


FrameRect 
PaintRect 
EraseRect 
InvertRect 
FillRect 
ScrollRect 
XferRect 
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pat: Pattern); 
Rect; dh,dv: INTEGER; updateRgn: rgnHandle); 


BitMap; srcRect,dstRect: Rect; 


mode:INTEGER; pat:Pattern); 
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Operations on Ovals 
PROCEDURE (r: Rect); 
PROCEDURE PaintOval (r: Rect); 
PROCEDURE EraseQOval (r: Rect); 
PROCEDURE InvertOval (r: Rect); 
PROCEDURE FillOval (r: Rect; pat: Pattern); 


Graphic Operations on Rounded-Corner Rectangles 
PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 
PROCEDURE PaintRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 
PROCEDURE EraseRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 
PROCEDURE InvertRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 
PROCEDURE FillRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER; pat: Pattern); 


Calculations with Regions 
FUNCTION NewRgn: RgnHandle; 
PROCEDURE DisposeRgn(rgn: RgnHandle); 
PROCEDURE CopyRen (srcRgn,dstRgn: RgnHandle); 
PROCEDURE SetRectRgn(rgn: RgnHandle; left,top,right,bottom: INTEGER); 
PROCEDURE RectRen (rgn: RgnHandle; r: Rect); 
PROCEDURE OpenRegn3; ss 
PROCEDURE CloseRgn (dstRgn: RgnHandle); 
PROCEDURE OffsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 
PROCEDURE InsetRen (rgn: RgnHandle; dh,dv: INTEGER); 
PROCEDURE SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 
PROCEDURE UnionRen (srcRgnA,srcRgnB,dstRgn: RgnHandle); 
PROCEDURE DiffRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 
PROCEDURE XorRgn (srcRgnA,srcRgenB,dstRgn: RgnHandle); 
FUNCTION PtInRgn (pt: Point; rgn: RgnHandle): BOOLEAN; 
FUNCTION RectInRgn (r: Rect; rgn: RgnHandle): BOOLEAN; 
FUNCTION EqualRgn (rgnA, rgnB: RgnHandle): BOOLEAN; 
FUNCTION EmptyRgn (rgn: RgnHandle): BOOLEAN; 


Graphic) Operations on Regions 


PROCEDURE FrameRgn (rgn: RgnHandle); 

PROCEDURE PaintRgn (rgn: RgnHandle); 

PROCEDURE EraseRgn (rgn: RgnHandle); 

PROCEDURE InvertRgn (rgn: RgnHandle); 

PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern); 

PROCEDURE XferRgn (srcBits,dstBits: BitMap; srcRect,dstRect: Rect; 
a ir a maskRgn: RgnHandle); 


ul U4 


Miscellaneous Utility Routines 
FUNCTION Random: INTEGER; 
FUNCTION GetPixel (h,v: INTEGER): BOOLEAN; 
PROCEDURE AddPt (src: Point; VAR dst: Point);3- 
PROCEDURE SubPt (src: Point; VAR dst: Point); 
PROCEDURE SetPt (VAR pt: Point; h,v: INTEGER); 
PROCEDURE LocalToGlobal (VAR pt: Point); 
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PROCEDURE GlobalToLocal (VAR pt: Point); 
PROCEDURE Stuf fHex (thingptr: WordFtr; s:Str255); 


DEFAULT VALUES 


These default values are set when you initialize MacGraf with the 
InitGraf procedure: en 


Global Type Setting 

white Pattern All-white pattern 

black Pattern All-black pattern 

gray Pattern 50% grey pattern 

1tGray Pattern 33% grey pattern 

dkGray Pattern 66% grey pattern 

arrow Cursor Pointing arrow cursor £ 
charNormal charStyle NO FONT, OR mode, no extras 
screenBits BitMap Macintosh screen, (%,9,384, 256) 
thePort GrafPtr NIL 

rgnSave BOOLEAN FALSE 


These default values for a single GrafPort are set by OpenPort: 


Variable Type Setting 

portBits BitMap ScreenBits (see InitGraf) 
portRect Rect ScreenBits.bounds (9,6,384, 256) 
visRgn** Region Rectangular, (9,9, 384,256) 
clipRgn** Region Rectangular, (-34660,-36664, 36666, 36660) 
bkPat Pattern White 

chStyle CharStyle CharNormal 

pnLoc Point (9,9) 

pnSize Point (1,1) 

pnMode INTEGER patCopy (8) 

pnPat Pattern Black 
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